home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 / MACD 5.bin / workbench / monitory / sysmon / docs / sysmon_lib.doc
Text File  |  1995-11-05  |  12KB  |  387 lines
  1. TABLE OF CONTENTS
  2.  
  3. sysmon.library/smFindTaskInfo
  4. sysmon.library/smFreeze
  5. sysmon.library/smGetTaskInfo
  6. sysmon.library/smHalt
  7. sysmon.library/smNextTaskInfo
  8. sysmon.library/smSleep
  9. sysmon.library/smUnFreeze
  10. sysmon.library/smVKPrintf
  11. sysmon.library/smVSPrintf
  12. sysmon.library/smVSysLog
  13. sysmon.library/smFindTaskInfo                   sysmon.library/smFindTaskInfo
  14.  
  15.    NAME    
  16.      smFindTaskInfo -- Find TaskInfo structure by Task Name. (V0)
  17.  
  18.    SYNOPSIS
  19.     tinfo = smFindTaskInfo( name )
  20.     D0                      A1
  21.  
  22.     struct TaskInfo *smFindTaskInfo( STRPTR name );
  23.  
  24.    FUNCTION
  25.     This function will search the TaskInfo Hash Table for a task with the
  26.     given name, and return a pointer to its TaskInfo structure. If a NULL
  27.     name pointer is given, a pointer to the TaskInfo of the current task
  28.     will be returned.
  29.  
  30.    INPUTS
  31.      name  - pointer to a NULL terminated string.
  32.     
  33.    RESULT
  34.      tinfo - A pointer to the corresponding TaskInfo structure or NULL
  35.             for an error (TaskInfo structure not found).
  36.  
  37.    NOTES
  38.     Unlike the exec.library/FindTask() function, this call does not
  39.     need to Disable() interrupts during search. It still needs to
  40.     Forbid() task switching though.
  41.  
  42.    BUGS
  43.  
  44.    SEE ALSO
  45.     exec.library/FindTask(), sysmon.library/smGetTaskInfo(),
  46.     sysmon.library/smNextTaskInfo()
  47. sysmon.library/smFreeze                               sysmon.library/smFreeze
  48.  
  49.    NAME    
  50.      smFreeze -- Put a task out of schedule. (V0)
  51.  
  52.    SYNOPSIS
  53.     success = smFreeze( task )
  54.     D0                  A1
  55.  
  56.     BOOL smFreeze( struct Task *task );
  57.  
  58.    FUNCTION
  59.     Put a task into the TaskFrozen list. The task will no longer be
  60.     dispatched and will not respond to signals (including exception
  61.     signals). However, these signals are not lost ; they will be
  62.     processed when the task comes out of the frozen state.
  63.  
  64.    INPUTS
  65.      task  - A pointer to a Task structure. If NULL, the current task
  66.         will be frozen.
  67.     
  68.    RESULT
  69.      success - A boolean value indicating the success of the operation.
  70.               This call will fail if for example, the Task was already
  71.           frozen
  72.  
  73.    NOTES
  74.     This function may be called from interrupts with a non-NULL task
  75.     pointer.
  76.     This call is potentially dangerous. Freezing another task may lead
  77.     to deadlocks if the task was performing critical operations under
  78.     semaphore protection when it was frozen. So do not freeze another
  79.     task without good reasons.
  80.     When freezing yourself, make sure someone will bring you back to
  81.     life by calling smUnFreeze() on you.
  82.  
  83.    BUGS
  84.  
  85.    SEE ALSO
  86.     sysmon.library/smUnFreeze() , exec.library/Wait()
  87.  
  88. sysmon.library/smGetTaskInfo                     sysmon.library/smGetTaskInfo
  89.  
  90.    NAME    
  91.      smGetTaskInfo -- Get pointer to TaskInfo structure. (V0)
  92.  
  93.    SYNOPSIS
  94.     tinfo = smGetTaskInfo( task )
  95.     D0                     A0
  96.  
  97.     struct TaskInfo *smGetTaskInfo( struct Task *task );
  98.  
  99.    FUNCTION
  100.     Get a pointer to the TaskInfo structure associated to a given
  101.     Task.
  102.  
  103.    INPUTS
  104.      task  - A pointer to a Task structure. If NULL, the TaskInfo
  105.         structure of the current task will be returned.
  106.     
  107.    RESULT
  108.      tinfo - A pointer to the corresponding TaskInfo structure or NULL
  109.             for an error (TaskInfo structure not found).
  110.  
  111.    NOTES
  112.  
  113.    BUGS
  114.  
  115.    SEE ALSO
  116.     sysmon.library/smFindTaskInfo(), sysmon.library/smNextTaskInfo().
  117.  
  118. sysmon.library/smHalt                                   sysmon.library/smHalt
  119.  
  120.    NAME    
  121.      smHalt -- Halts the system for safe power down. (V0)
  122.  
  123.    SYNOPSIS
  124.     smHalt( flags )
  125.         D0
  126.  
  127.     void smHalt( ULONG flags );
  128.  
  129.    FUNCTION
  130.     This function will disable multitasking, blink the power LED, kill all
  131.     tasks except the caller, then display a guru like deadend alert saying
  132.     'System Shutdown Complete' (without time out).
  133.     It is then safe to turn the power off.
  134.     If the user presses a mouse button to cancel the alert, the system
  135.     will reset via exec.library/ColdReboot().
  136.     If the DEL key (ASCII $7f) is pressed on a serial port terminal while
  137.     the power LED is blinking, control will be transfered to the ROM
  138.     debugger (ROM-Wack for V37, SAD for V39+)
  139.     In any case, this function never returns.
  140.  
  141.    INPUT
  142.      flags  - A bit pattern specifying options. Currently defined are :
  143.          HALTB_REBOOT : The alert is not displayed, causing the system
  144.          to reboot immediately.
  145.          HALTB_REKICK : Forces MMU-SoftKicked machines to reload
  146.          KickStart by disabling the MMU before rebooting. This
  147.          requires a 68020 or greater CPU with a working MMU.
  148.     
  149.    WARNING
  150.     This function does not care about filesystem consistency or whatever
  151.     other tasks are doing when it is called. It is the responsability of
  152.     the caller to take appropriate precautions before calling this
  153.     function.
  154.  
  155.    BUGS
  156.  
  157.    SEE ALSO
  158.     exec.library/ColdReboot(), exec.library/Alert()
  159. sysmon.library/smNextTaskInfo                   sysmon.library/smNextTaskInfo
  160.  
  161.    NAME    
  162.      smNextTaskInfo -- Get the next TaskInfo entry. (V0)
  163.  
  164.    SYNOPSIS
  165.     newtinfo = smNextTaskInfo( tinfo )
  166.     D0                         A1
  167.  
  168.     struct TaskInfo *smNextTaskInfo( struct TaskInfo *tinfo );
  169.  
  170.    FUNCTION
  171.     This function returns the next TaskInfo structure in the Hash Table,
  172.     or NULL if there is no next entry.
  173.  
  174.    INPUT
  175.      tinfo  - Pointer to the current TaskInfo structure. If NULL, the
  176.          first TaskInfo structure will be returned.
  177.     
  178.    RESULT
  179.      newtinfo - A pointer to the next TaskInfo in the table, or NULL if
  180.            the end has been reached.
  181.  
  182.    WARNING
  183.     This function does not arbitrate for access to the TaskInfo HashTable.
  184.     You must be in Forbid() when calling it.
  185.  
  186.    BUGS
  187.  
  188.    SEE ALSO
  189.     exec.library/FindTask(), sysmon.library/smGetTaskInfo(),
  190.     sysmon.library/smFindTaskInfo()
  191. sysmon.library/smSleep                                 sysmon.library/smSleep
  192.  
  193.    NAME    
  194.      smSleep -- Put a task into hibernation for a specified time. (V0)
  195.  
  196.    SYNOPSIS
  197.     success = smSleep( ticks )
  198.     D0                 D0
  199.  
  200.     BOOL smSleep( ULONG ticks );
  201.  
  202.    FUNCTION
  203.     This function freezes the current task for the specified period of
  204.     time. 
  205.  
  206.    INPUTS
  207.      ticks  - The number of ticks (50 per second) the task will sleep.
  208.          If ZERO, the function will return immediately.
  209.     
  210.    RESULT
  211.      success - A boolean value indicating the success of the operation.
  212.               It may fail in very low memory conditions, in that case
  213.           the function returns immediately.
  214.  
  215.    NOTES
  216.     This function uses the VBLANK unit of the timer.device with a
  217.     PA_SOFTINT reply port.
  218.     Because of the granularity of the VBLANK timer and the behaviour of
  219.     the frozen state, short delays may be inaccurate.
  220.  
  221.    BUGS
  222.  
  223.    SEE ALSO
  224.     dos.library/Delay(), sysmon.library/smFreeze(),
  225.     sysmon.library/smUnFreeze()
  226.  
  227. sysmon.library/smUnFreeze                           sysmon.library/smUnFreeze
  228.  
  229.    NAME    
  230.      smUnFreeze -- Put a frozen task back to life. (V0)
  231.  
  232.    SYNOPSIS
  233.     success = smUnFreeze( task )
  234.     D0                    A1
  235.  
  236.     BOOL smUnFreeze( struct Task *task );
  237.  
  238.    FUNCTION
  239.     Put a frozen task back into the ready or waiting list. If the task
  240.     has received signals when it was frozen, they will be precessed now.
  241.     
  242.    INPUTS
  243.      task  - A pointer to a Task structure.
  244.     
  245.    RESULT
  246.      success - A boolean value indicating the success of the operation.
  247.               This call will fail if the Task was not frozen.
  248.  
  249.    NOTES
  250.     This function may be called from interrupts.
  251.     The frozen state is not intended for short time waits or realtime
  252.     processing, so there is no guarantee that the unfrozen task will
  253.     restart processing immediately, even if its priority is greater
  254.     than the priority of the calling task.
  255.  
  256.    BUGS
  257.  
  258.    SEE ALSO
  259.     sysmon.library/smFreeze(), exec.library/Wait(), exec.library/Signal()
  260.  
  261. sysmon.library/smVKPrintf                           sysmon.library/smVKPrintf
  262.  
  263.    NAME    
  264.      smVKPrintf -- print formatted data to the debugging console. (V0)
  265.               (defaults to the serial port at 9600 baud)
  266.  
  267.    SYNOPSIS
  268.     smVKPrintf( format, values )
  269.                 A0      A1
  270.  
  271.     VOID smVKPrintf(STRPTR format, APTR values);
  272.  
  273.    FUNCTION
  274.     Print a formatted C-type string to the debugging console.
  275.     See the exec.library/RawDoFmt() call for the supported % formatting
  276.     commands.
  277.  
  278.    INPUTS
  279.      format - A C style string with % commands to indicate where parameters
  280.          are to be inserted.
  281.     values - A pointer to an array of parameters, to be inserted into
  282.          specified places in the string.
  283.     
  284.    RESULT
  285.     NONE
  286.  
  287.    NOTES
  288.     RawDoFmt assumes 16 bit ints, so you will usually need 'l's in your
  289.     formats (ex: %ld versus %d).
  290.     This function may be called from interrupts.
  291.  
  292.    BUGS
  293.     The exec.library/RawPutChar() called by this function will busy wait
  294.     when a ^S character is typed at the remote console. This will hang
  295.     the system if smVKPrintf() was called from a Forbid()/Disable()
  296.     section or from supervisor mode. Type ^Q at the remote terminal to
  297.     resume output.
  298.  
  299.    SEE ALSO
  300.     dos.library/VPrintf(), exec.library/RawDoFmt(), debug.lib/KPrintF()
  301.  
  302. sysmon.library/smVSPrintf                           sysmon.library/smVSPrintf
  303.  
  304.    NAME    
  305.      smVSPrintf -- format data to a character buffer. (V0)
  306.  
  307.    SYNOPSIS
  308.     endstr = smVSPrintf( buffer, format, values )
  309.     D0                   A3      A0      A1
  310.  
  311.     APTR smVSPrintf(STRPTR buffer, STRPTR format, APTR values);
  312.  
  313.    FUNCTION
  314.     Print a formatted C-type string to a character buffer.
  315.     See the exec.library/RawDoFmt() call for the supported % formatting
  316.     commands.
  317.  
  318.    INPUTS
  319.     buffer - A pointer to a buffer large enough to contain the resulting
  320.          string.
  321.      format - A C style string with % commands to indicate where parameters
  322.          are to be inserted.
  323.     values - A pointer to an array of parameters, to be inserted into
  324.          specified places in the string.
  325.     
  326.    RESULT
  327.      endstr - A pointer to the end of the formatted data.
  328.  
  329.    NOTES
  330.     RawDoFmt assumes 16 bit ints, so you will usually need 'l's in your
  331.     formats (ex: %ld versus %d).
  332.     This function may be called from interrupts.
  333.  
  334.    BUGS
  335.  
  336.    SEE ALSO
  337.     dos.library/VPrintf(), exec.library/RawDoFmt(), ANSI-C sprintf()
  338.  
  339. sysmon.library/smVSysLog                             sysmon.library/smVSysLog
  340.  
  341.    NAME    
  342.      smVSysLog -- Logs system messages to file or console. (V0)
  343.  
  344.    SYNOPSIS
  345.     success = smVSysLog( priority, format, values )
  346.     D0                   D0        A0      A1
  347.  
  348.     BOOL smVSysLog(ULONG priority, STRPTR format, APTR values);
  349.     BOOL smSysLog(ULONG priority, STRPTR format, ...);
  350.  
  351.    FUNCTION
  352.     Formats a system message via exec.library/RawDoFmt() and logs it
  353.     into a disk file and/or window and/or serial terminal based on
  354.     it's priority value and user defined thresholds.
  355.  
  356.    INPUTS
  357.     priority - A priority value and optional flags as defined in sysmon.i .
  358.            Low values mean high severity.
  359.            LOG_NOHEAD can be used to write long messages in several
  360.            parts by skipping the header for subsequent calls.
  361.            LOG_NOWIN and LOG_NOFILE disable window and file logging
  362.            respectively in cases where it is not appropriate.
  363.      format - A C style string with % commands to indicate where parameters
  364.          are to be inserted.
  365.     values - A pointer to an array of parameters, to be inserted into
  366.          specified places in the string.
  367.     
  368.    RESULT
  369.      success - A boolean value. TRUE for success, FALSE for an error.
  370.  
  371.    NOTES
  372.     The Sysmon.server process must be running for this call to succeed.
  373.     The format buffer is limited to SM_MAXLOGCHARS chars, so make sure
  374.     your formatted string will not cause it to overflow.
  375.     The higher severity codes (LOG_EMERG and LOG_ALERT) are reserved for
  376.     system failures and should not be used by applications.
  377.     This function may return before logging is complete.
  378.     This function may be called from interrupts.
  379.     
  380.    BUGS
  381.     If the format buffer overflows, havoc will break out.
  382.  
  383.    SEE ALSO
  384.     exec.library/RawDoFmt(), sysmon.library/smVKPrintf(),
  385.     sysmon.library/smVSPrintf()
  386.  
  387.